ATOM Documentation

Capability System

The Capability System defines what agents can do, mapping skills and components to granular permissions that enable governance and maturity-based access control.

Overview

Capabilities bridge the gap between agent skills and governance, providing fine-grained control over what actions agents can perform based on their maturity level and training.

Skills vs Capabilities

**Important Distinction:**

**How They Work Together:**

Skills (Basic Units) → Combined into → Capabilities (Higher-Level Competencies)
    ↓                                          ↓
Individual tools like:                 "Data Analysis" capability includes:
- Text summarization                    - Data visualization
- Sentiment analysis                    - Chart generation
- Data extraction                       - Report generation
                                          Domain: DATA_ANALYSIS
                                          Risk factor: 0.3
                                          Threshold: 70% success rate

**Key Differences:**

1. **Skills** are the fundamental building blocks - individual functions you can install and use from the marketplace
2. **Capabilities** are higher-level competencies that agents develop by combining multiple skills through training
3. **Skills** have safety-based governance (LOW_RISK/HIGH_RISK) and require admin approval for dangerous operations
4. **Capabilities** have domain-based governance with graduation thresholds for agent maturity progression
5. **Skills** are installed from the marketplace; **Capabilities** are developed by agents through training and experience

**Example:**

To become a "Data Analysis Specialist," an agent needs:

• **Skills installed**: Data extraction, Chart rendering, Report generation (from marketplace)
• **Capabilities developed**: DATA_ANALYSIS domain proficiency (through training and success rate)

Core Concepts

What are Capabilities?

Capabilities are specific actions or permissions that agents can perform. Examples include:

• **Data Operations**: Query databases, generate reports, create visualizations
• **Code Execution**: Run scripts, access terminal, execute commands
• **Integrations**: Make API calls, handle webhooks, connect to external services
• **Communication**: Send emails, post messages, trigger notifications

Capability Types

Functional Domains

Capabilities are organized into domains that govern agent access and maturity progression.

System Domains (4 Core Domains)

The platform provides 4 core system domains with predefined governance rules:

**Risk Factors:**

• **0.0-0.3 (Low Risk)**: Data analysis, reasoning - can be used by student-level agents
• **0.4-0.6 (Medium Risk)**: Integrations - requires intern-level or higher
• **0.7-1.0 (High Risk)**: Code execution - requires supervised or autonomous level

Tenant-Created Domains (Custom Governance)

Tenants can create custom domains for specialized use cases, extending governance beyond the 4 core system domains:

**Features:**

• **Custom Risk Factors**: Define domain-specific risk levels (0.0-1.0) with automatic governance controls
• **Custom Thresholds**: Set graduation thresholds for student/intern/supervised levels
• **Domain Inheritance**: Inherit configuration from parent domains (system or custom)
• **Tenant Isolation**: Custom domains are tenant-specific and respect multi-tenancy
• **Marketplace Sharing**: Publish custom domains to the domain marketplace for other tenants

**Use Cases:**

• **Industry-Specific Domains**: Healthcare, finance, legal compliance
• **Company-Specific Domains**: Internal workflows, proprietary systems
• **Integration Categories**: CRM, ERP, marketing automation
• **Specialized Capabilities**: ML operations, data engineering, security

**Example Custom Domain:**

Domain: ML_Operations
Risk Factor: 0.6 (Medium-High)
Graduation Thresholds:
  - Student: 75% success rate
  - Intern: 85% success rate
  - Supervised: 93% success rate
Parent Domain: CODE_EXECUTION (inherits base capabilities)
Capabilities: model_training, model_deployment, experiment_tracking

**Governance Enforcement:**

All domains (system and custom) enforce governance through:

• **Capability Checks**: Agents must have capabilities in the domain
• **Maturity Verification**: Agent maturity must meet domain thresholds
• **Risk-Based Controls**: Automatic approval requirements based on risk factor
• **Rate Limiting**: Usage quotas enforced per domain (scaled by risk)
• **Audit Logging**: All domain actions logged based on risk level
• **Compliance Notifications**: Automatic notifications for high-risk domains

Risk Factor-Based Governance (NEW)

Risk factors (0.0-1.0) now automatically control governance behavior for regulated industries:

**How Risk Factors Work:**

1. **Automatic Approval Requirements**:

• LOW (0.0-0.3): Standard governance, no special approval
• MEDIUM (0.4-0.6): Supervisor notification required
• HIGH (0.7-0.8): Dual human approval required
• CRITICAL (0.9-1.0): Manual approval + compliance officer notification

1. **Rate Limit Adjustments**:

• Base rate limit × multiplier (based on risk)
• Example: 1000 requests/hour → CRITICAL (0.2) → 200 requests/hour

1. **Audit Logging Levels**:

• **Basic**: Standard action logging
• **Enhanced**: Detailed request/response logging
• **Strict**: Full context logging with user identity
• **Full Compliance**: Regulatory-grade audit trail (HIPAA, SOX)

1. **Retention Periods**:

• LOW: 90 days (3 months)
• MEDIUM: 365 days (1 year)
• HIGH: 2555 days (7 years)
• CRITICAL: 3650 days (10 years)

Strict Override Principle (NEW)

**Custom domains can enforce stricter requirements than system defaults.**

The platform follows the **MAX(strictness)** principle: always use the stricter of system or custom requirements.

**What Gets Overridden:**

1. **Graduation Thresholds**: Higher threshold wins (stricter)

• Custom domain: 95% success rate
• System parent: 90% success rate
• **Result**: 95% is used (stricter)

1. **Risk Factors**: Higher risk factor wins (stricter controls)

• Custom domain: 0.95 (CRITICAL)
• System parent: 0.50 (MEDIUM)
• **Result**: 0.95 is used (stricter controls apply)

1. **Multi-Level Inheritance**: Transitive strict override

• Base system domain → Custom domain 1 → Custom domain 2
• Each level can increase strictness
• Final result uses the strictest values from entire chain

**Example: Healthcare Domain Stricter Than Parent**

Parent Domain: DATA_ANALYSIS (system)
- Student threshold: 70%
- Risk factor: 0.3 (LOW)

Custom Domain: Healthcare_Analytics
- Inherits from: DATA_ANALYSIS
- Student threshold: 85% (stricter!)
- Risk factor: 0.95 (CRITICAL - stricter!)

Effective Requirements (MAX strictness):
- Student threshold: 85% (custom domain's stricter value)
- Risk factor: 0.95 (custom domain's stricter value)
- Controls: Manual approval, 20% rate limits, 10-year retention

**Example: Payment Processing Stricter Than Parent**

Parent Domain: INTEGRATIONS (system)
- Intern threshold: 85%
- Supervised threshold: 92%
- Risk factor: 0.5 (MEDIUM)

Custom Domain: Payment_Integrations
- Inherits from: INTEGRATIONS
- Intern threshold: 95% (stricter!)
- Supervised threshold: 98% (stricter!)
- Risk factor: 0.85 (HIGH - stricter!)

Effective Requirements (MAX strictness):
- Intern threshold: 95% (custom domain's stricter value)
- Supervised threshold: 98% (custom domain's stricter value)
- Risk factor: 0.85 (custom domain's stricter value)
- Controls: Dual approval, 40% rate limits, 7-year retention

**Why This Matters:**

Regulated industries often have stricter requirements than general-purpose domains:

• **Healthcare**: HIPAA requires 99%+ accuracy for PHI access
• **Finance**: SOX requires dual approval for financial reporting
• **Legal**: Attorney-client privilege requires enhanced logging
• **Insurance**: State regulations require strict audit trails

The strict override principle ensures custom domains can enforce these stricter requirements without modifying system defaults.

**Example: Healthcare Compliance Domain**

Domain: Healthcare_Compliance
Risk Factor: 0.95 (CRITICAL)

Automatic Controls Applied:
✓ Manual approval required for all actions
✓ Dual human approval (two reviewers)
✓ Compliance officer automatically notified
✓ Rate limit reduced to 20% of normal
✓ Full compliance audit logging (HIPAA-grade)
✓ 10-year audit log retention
✓ All actions tagged with healthcare compliance metadata

How Capabilities Work

Capability Development

Agents develop capabilities through:

1. **Skill Installation**: Installing skills provides the foundation for capability development
2. **Experience Accumulation**: Successful execution of tasks builds capability proficiency
3. **Domain Mastery**: Agents graduate through capability levels based on success rates
4. **Maturity Progression**: Higher maturity levels unlock access to more advanced capabilities

**Capability Graduation:**

Each domain has specific success rate thresholds for capability levels:

Governance Enforcement

Before an agent performs an action, the system checks:

1. **Capability Existence**: Does the agent have this capability?
2. **Maturity Check**: Is the agent's maturity level sufficient?
3. **Rate Limits**: Has the agent exceeded usage quotas?
4. **Tenant Permissions**: Is the capability allowed for this tenant?

Capability Inference

The system automatically discovers capabilities from:

• **Component Analysis**: Examines what canvas components do
• **Skill Metadata**: Extracts capability information from skill definitions
• **Usage Patterns**: Learns from actual agent behavior

Usage Patterns

Capability Development

Capabilities are developed through training and experience:

• **Installing skills**: Provides the building blocks for capability development
• **Executing tasks**: Successful execution builds proficiency and tracks success rates
• **Meeting thresholds**: Reaching domain-specific success rates unlocks higher capability levels
• **Graduation exams**: Formal validation of capability mastery for maturity progression

Checking Permissions

Before executing actions, agents verify they have the required capability:

Agent wants to execute code
    ↓
Check: Does agent have "code_execution" capability?
    ↓
Check: Is agent maturity ≥ "supervised"?
    ↓
Check: Is code execution within rate limits?
    ↓
Execute or Deny

Capability Profiling

Track agent capabilities by:

• **Domain Coverage**: Which functional domains the agent operates in
• **Proficiency Level**: How skilled the agent is with each capability
• **Usage Frequency**: How often capabilities are used
• **Success Rate**: Success vs. failure ratios

Maturity and Capabilities

Different maturity levels have different capability access:

Domain Marketplace

The domain marketplace enables tenants to share and discover custom domains across the platform:

Marketplace Features

• **Domain Submission**: Publish custom domains for other tenants to discover
• **Admin Approval**: All submissions reviewed for quality and safety
• **Domain Installation**: Install domain templates with custom configurations
• **Rating System**: Rate and review domains based on effectiveness
• **Search & Discovery**: Find domains by category, tags, or popularity

Publishing Workflow

1. Create Custom Domain
   ↓
2. Submit to Marketplace (pending approval)
   ↓
3. Admin Review (safety, quality, documentation)
   ↓
4. Approval → Listed in Marketplace
   ↓
5. Other Tenants Install (creates tenant-specific instance)

Installing Domains

When installing a domain from the marketplace:

• **Template Copy**: Creates a new domain instance for your tenant
• **Customization**: Rename and configure thresholds for your needs
• **Capability Inheritance**: Includes all capabilities from the template
• **Independent Governance**: Your tenant's instance operates independently

Governance Integration

All marketplace domains integrate with the governance system:

• **Risk Factors**: Inherited from template (can be adjusted)
• **Graduation Thresholds**: Inherited from template (can be customized)
• **Capability Mappings**: Automatically included in capability matrix
• **Agent Assignments**: Agents can be assigned to marketplace domains

**Example:**

Tenant A creates "Healthcare_Compliance" domain
  → Submits to marketplace
  → Tenant B installs as "My_Healthcare_Compliance"
  → Tenant B adjusts thresholds to be stricter
  → Both tenants use domain independently with their own governance rules

API Overview

Domain Management

**System Domains:**

• List all available capability domains (system + tenant-created)
• Get domain metadata (descriptions, risk factors, thresholds)
• View domain progression metrics

**Custom Domains:**

• Create custom domains for your tenant
• Update domain configuration (risk factors, thresholds)
• Delete custom domains
• Inherit from parent domains (system or custom)

**Marketplace:**

• Submit domains to marketplace
• Browse marketplace domains
• Install domain templates
• Rate and review domains

Capability Management

• List all available capabilities
• Get details about specific capabilities
• Create custom capabilities
• Update capability definitions

Agent Capabilities

• View agent's assigned capabilities
• Add capabilities to agents
• Remove capabilities from agents
• Check if agent can perform specific action

Capability Matrix

• View capability matrix across all agents
• Get agent capability profile
• Check domain proficiency
• Analyze capability usage patterns

Capability Feedback

• Submit feedback on capability execution
• View capability success rates
• Identify capabilities needing improvement

Creating Custom Domains

When to Create Custom Domains

Create custom domains when:

• **Industry Requirements**: Specialized compliance or regulatory needs
• **Proprietary Workflows**: Company-specific processes and systems
• **Advanced Integration**: Complex multi-step integration scenarios
• **Specialized AI**: ML operations, data engineering, or security workflows

Choosing the Right Risk Factor

Select risk factor based on industry regulations and potential impact:

**Industry-Specific Examples:**

**Healthcare (HIPAA):**

Domain: Healthcare_PHI_Access
Risk Factor: 0.95 (CRITICAL)
Controls:
  - Manual approval required
  - Full compliance audit logging
  - 10-year retention (HIPAA requirement)
  - Compliance officer notified on all access

**Legal (Attorney-Client Privilege):**

Domain: Legal_Document_Access
Risk Factor: 0.90 (CRITICAL)
Controls:
  - Manual approval for privileged documents
  - Enhanced audit logging
  - 7-year retention (bar association requirements)
  - Attorney notification on access

**Insurance (Claims Processing):**

Domain: Insurance_Claims_Auto
Risk Factor: 0.75 (HIGH)
Controls:
  - Dual approval for claim payouts
  - Strict audit logging
  - 7-year retention (state insurance regulations)
  - Supervisor notification on large claims

**Finance (SOX Compliance):**

Domain: Finance_Financial_Reporting
Risk Factor: 0.85 (HIGH)
Controls:
  - Dual approval for financial statements
  - Strict audit logging with full context
  - 7-year retention (SOX requirement)
  - CFO notification on reports

Domain Creation Process

**1. Define Domain Metadata:**

Domain Name: "Healthcare_Compliance"
Description: "HIPAA-compliant healthcare data processing"
Risk Factor: 0.6 (medium-high risk)
Parent Domain: "DATA_ANALYSIS" (inherits base capabilities)

**2. Set Graduation Thresholds:**

Student Threshold: 0.75 (75% success rate required)
Intern Threshold: 0.85 (85% success rate required)
Supervised Threshold: 0.93 (93% success rate required)

**3. Define Capabilities:**

- phi_data_access (permission)
- hipaa_audit_logging (action)
- patient_data_anonymization (tool)
- compliance_reporting (action)

**4. Publish to Marketplace (Optional):**

- Submit for admin approval
- Set pricing (free or paid)
- Add tags: healthcare, hipaa, compliance
- Provide documentation and examples

Example: Creating a Finance Domain

# API Call to create custom domain
POST /api/v1/domains/create
{
  "domain_name": "Finance_Operations",
  "domain_slug": "finance_operations",
  "description": "Financial data processing and reporting",
  "risk_factor": 0.65,
  "parent_domain_id": "data_analysis_system_id",
  "graduation_thresholds": {
    "student": 0.80,
    "intern": 0.88,
    "supervised": 0.95
  },
  "capabilities": [
    "financial_reporting",
    "transaction_processing",
    "audit_trail_generation"
  ]
}

Best Practices

1. **Start Small**: Grant minimal capabilities, expand as agent proves competence
2. **Domain Alignment**: Group related capabilities under appropriate domains
3. **Monitor Usage**: Track which capabilities are used most/least
4. **Regular Reviews**: Periodically audit and update capability assignments
5. **Progressive Expansion**: Add capabilities as agents demonstrate success
6. **Custom Domain Strategy**: Create custom domains for specialized use cases, use system domains for general capabilities
7. **Inheritance Leverage**: Inherit from system domains when appropriate to reduce configuration overhead
8. **Marketplace Contribution**: Share useful custom domains to help other tenants

Common Scenarios

Creating a Data Analyst Agent

Required Capabilities:
- data_visualization (tool)
- chart_rendering (tool)
- data_query (action)
- report_generation (action)

Required Maturity: Intern or higher

Domain: DATA_ANALYSIS (system domain)
Risk Factor: 0.3 (LOW)
Controls: Standard governance, no special approval

Creating an Integration Specialist

Required Capabilities:
- api_call (action)
- webhook_handler (action)
- data_connector (tool)
- authentication_management (permission)

Required Maturity: Supervised or higher

Domain: INTEGRATIONS (system domain)
Risk Factor: 0.5 (MEDIUM)
Controls: Enhanced logging, supervisor notification, 70% rate limit

Creating a Healthcare Compliance Agent

Required Capabilities:
- phi_data_access (permission)
- hipaa_audit_logging (action)
- patient_data_anonymization (tool)
- compliance_reporting (action)

Required Maturity: Supervised or higher

Domain: Healthcare_Compliance (custom domain)

Custom Thresholds:
- Student: 75% success rate (stricter than system domains)
- Intern: 85% success rate
- Supervised: 93% success rate
- Autonomous: 98% success rate (HIPAA requires highest accuracy)

Risk Factor: 0.95 (CRITICAL)
Parent Domain: DATA_ANALYSIS (inherits base capabilities)

Automatic Risk-Based Controls:
✓ Manual approval required for all PHI access
✓ Dual human approval (two reviewers required)
✓ Compliance officer automatically notified
✓ Rate limit reduced to 20% of normal
✓ Full compliance audit logging (HIPAA-grade)
✓ 10-year audit log retention

Creating a Legal Document Agent

Required Capabilities:
- document_classification (action)
- privilege_scan (tool)
- attorney_review_request (action)
- client_communication (permission)

Required Maturity: Autonomous or higher

Domain: Legal_Document_Access (custom domain)

Custom Thresholds:
- Student: 80% success rate
- Intern: 90% success rate
- Supervised: 95% success rate
- Autonomous: 99% success rate (legal requires highest accuracy)

Risk Factor: 0.90 (CRITICAL)
Parent Domain: REASONING (inherits base capabilities)

Automatic Risk-Based Controls:
✓ Manual approval for privileged documents
✓ Full compliance audit logging
✓ 7-year retention (bar association requirements)
✓ Attorney notification on privileged document access
✓ Rate limit reduced to 20% of normal

Installing a Marketplace Domain

Scenario: Your company needs ML operations capabilities

1. Browse Marketplace
   - Search for "ML_Operations"
   - Review ratings and documentation
   - Check install count and publisher reputation
   - Review risk factor and controls

2. Install Domain
   POST /api/v1/domains/marketplace/install
   {
     "template_domain_id": "ml_ops_template_id",
     "custom_name": "My_Company_ML_Ops"
   }

3. Customize Risk Factor (optional)
   - Adjust risk factor based on your requirements
   - Higher risk = stricter controls (more approvals, lower rate limits)
   - Lower risk = looser controls (faster operations)

4. Customize Thresholds (optional)
   - Adjust graduation thresholds for your requirements
   - Add company-specific capabilities

5. Assign to Agents
   - Assign ML-specialized agents to the domain
   - Track domain proficiency and usage
   - Monitor maturity progression

See Also

• Specialist Domains - Domain-based expertise and agent specialization
• Agent Maturity Levels - Maturity system details
• Entity System - Dynamic data structures
• Domain Marketplace API - API reference for domain operations
• Meta-Agent Routing - How domains route to specialist agents